Changing Properties

A change event is generated whenever a new value is entered for a property. It is also used to signal that a user-defined property needs changing. The event structure (WIDGET_PROPSHEET_CHANGE) provided when a change occurs contains a COMPONENT, an IDENTIFIER, a PROPTYPE, and a SET_DEFINED tag. The COMPONENT tag contains a reference to the object associated with the property sheet. When multiple objects are associated with the property sheet, this member indicates which object is to change. The IDENTIFIER tag specifies the value of the property’s identifier attribute. This identifier is unique among all of the component’s properties. The PROPTYPE tag indicates the type of the property (integer, string, etc.). Integer values for these types can be found in the documentation for components. The SET_DEFINED tag indicates whether or not an undefined property is having its value set. In most circumstances, along with its new value, the property should have its ‘UNDEFINED’ attribute set to zero. If a property is never marked as undefined, this field can be ignored.

Although the component’s object reference is included in the event structure, it can also be retrieved via the following call:

WIDGET_CONTROL, event.id, GET_VALUE = obj

where event is the event structure and obj is the object reference of the component.

The PROPTYPE field is provided for convenience. The property type should be known implicitly based on IDENTIFIER, but can be retrieved (in integer form) by:

obj->GetPropertyAttribute, event.identifier, TYPE = type

where obj is the object reference of the component, event is the event structure, and type represents the data type of the property. Here, the value returned in by the TYPE keyword is the same as the value of the PROPTYPE field of the widget event structure.

Properties can use their UNDEFINED attribute to show an indeterminate state (set attribute UNDEFINED = 1). This might arise after the aggregation of two or more properties. One could imagine a COLOR property representing both the border and the interior color of a polygon so that just one color property is displayed in the property sheet. When set, the chosen color would be applied to both, and then the following code could be used to mark the property as defined:

IF (event.set_defined) THEN $

   event.component->SetPropertyAttribute, $

      event.identifier, UNDEFINED = 0

WIDGET_CONTROL, event.id, REFRESH_PROPERTY = event.identifier

where event is the event structure.

Note: The REFRESH_PROPERTY keyword to WIDGET_CONTROL is used to refresh the property sheet. This is necessary because although the property sheet knows about its component, it does not directly change the component itself. Just as with changing properties values, the property sheet and underlying component have a clear boundary and can only affect each other through IDL statements.

Properties can also be hidden (removing them from the property sheet entirely) or desensitized (displaying the property in the property sheet, but not allowing the user to change its value).

Updating the Component

When a value has been changed in the property sheet, you can access this resulting value through the WIDGET_INFO function:

value = WIDGET_INFO(event.id, PROPERTY_VALUE = event.identifier)

where event is the event structure. This value can then be used to update the changed property in the component object by calling its SetPropertyByIdentifier method:

event.component->SetPropertyByIdentifier, event.identifier, $

   value

where event is the event structure and value is the modified property value.